System Booster/System Booster.iso/Archives/StartupTools/PicBoot2_3.lha/PicBoot.Man

Text File | 1994-08-30 | 25KB | 650 lines

   This file describes PicBoot, version 2.3, a program to show an IFF
ILBM or GIF picture during boot.

Introduction
************

   Have you removed all output in your 2.0+ startup, and only see a
black screen during boot? Wouldn't it be nice to have a picture
instead? A picture that disappeared when the Workbench screen opened?

   If so, PicBoot is certainly a program for you. What it will do is
to read any IFF file containing an ILBM picture - or a GIF file - and
show that picture. As soon as the Workbench screen appears (or you
press any mouse-button), the picture will go away.

   Features:

   *  Fast picture unpacking, using highly optimized assembler. The
     entire picture is read into memory and then unpacked. This applies
     both to the IFF and the GIF unpacker.

   *  Optional auto-detaching; the picture is loaded as fast as
     possible, with minimal memory fragmentation.

   *  A picture can be shown a user-specified time after the
     Workbench screen opens (see DELAY and PATCH).

   *  Extremely flexible argument parser.

   *  Random select among any number of pictures, in several different
     ways.

   *  Force a certain display mode for a picture, even if saved with
     another (can be selected on a picture by picture basis).

   *  The comment field of a file may be used to specify options.

   *  Optional screen centering (horisontally).

System requirements
*******************

   Apart from OS 2.04+, PicBoot doesn't require any special
libraries. The only non-ROM library required is iffparse.library
(which normally resides in Libs:).

       PicBoot have full support for OS 3.0+ and AGA graphics.

Legal information
*****************

   This program is freeware. You may copy and use this program freely,
as long as the following conditions are met:

   *  All files are copied in an unmodified state. If additional
     information is needed, place it in a separate file. Preferably
     redistribute in the original archive form (*.Lha).

     Exception: So called BBS ads may not be added!

   *  The copying is done on a non-commercial and non-profit basis
     only. A copy fee to cover media costs, postage etc. may be
     charged. This fee may not exceed the fee to obtain an AmigaLibDisk
     from Fred Fish.

   *  The copier/spreader is not claiming the Copyright © of this
     program.

   Any exceptions from these restrictions requires written permission
from the author, Magnus Holmgren (see Author contact).

Disclaimer
==========

   Magnus Holmgren neither assume nor accept any responsibility for the
use or misuse of these programs. He also will not be held liable for
damages or any compensation due to loss of profit or any other damages
arising out of the use, or inability to use these programs.

   Magnus Holmgren will not be liable for any damage arising from the
failure of these programs to perform as described, or any destruction
of other programs or data residing on a system attempting to run the
programs. While he know of no damaging errors, the user of these
programs uses it at his or her own risk.

Usage
*****

   To activate PicBoot, add a line to your S:Startup-Sequence,
looking something like this:

     PicBoot Pics:Hi-res/Calvin01.Pic DETACH

Or, if you have a list of files in "Work:Text/PicList":

     PicBoot Work:Text/PicList LIST DETACH

   Or, if your drawer Pics:BootPics contains some pictures:

     PicBoot Pics:BootPics/#?.(Pic|Gif) DETACH

   This line should be located near the beginning in the
S:Startup-Sequence (no point in placing it near the LoadWB command,
is it? :), but keep it after SetPatch. PicBoot will only output any
text if it fails, so don't re-direct its output. Note however that if
you place PicBoot before any additional monitors are installed,
you'll be stuck with the default.monitor for showing your picture. The
DEFAULT switch may be of help here.

   Make sure no program makes any output in the CLI window, since then
the Workbench screen will open with a boring CLI-window instead...

   Options:

FILES
=====

   This is the only required argument. Here you specify the name of the
picture you want to view. You may enter several files here, in which
case PicBoot will select one of them randomly, and show that one.

   The name(s) can also be the name of an ASCII file containing a
filename list if you specified the LIST option.

   The name(s) can also be the name of a drawer, in which case
PicBoot will randomly select one of the files in this drawer. To use
a pattern during this scanning, simply enter the pattern like it had
been the name of a file in the drawer. Example:

     Work:Pics/#?.gif

which would make PicBoot select a file ending in .gif in the drawer
Work:Pics

   If the comment field of the selected listfile or picture starts with
"*PicBoot*: " (case sensitive), then the rest of the comment is taken
to be arguments, like those in a LIST file.

   You may freely mix picture and drawer names. Listfiles can only be
mixed with the other two ones, if the comment contains the LIST switch.
In that case, the LIST argument should not be used on the command line
(or in a list file). Ofcourse you can random select among list files
with the "drawer scanner" if you like.. :)

MODEID
======

   Short form: M

   NOTE: This argument is mainly for the more "advanced" user.

   This argument should be a decimal number specifying which screen
mode to use.  It basically replaces the so called CAMG hunk in an ILBM
file (since it contains which screen mode to use). Thus, you must
select mode with care, or else the picture will look like trash
(nothing more serious can happen. I hope! :). When showing GIF files,
it will override the internal "best mode" routines (which aren't good
at all. But I haven't bothered to add code to make them better.. :).

   To make it easier for you to find out which display mode id to use,
there is a small program called GetModeID included, which uses the
ReqTools or Asl screenmode requester. Simply select the display mode
you want, and it will print out the number you should use here.  See
GetModeID.

   The mode id will be passed through the same validity checking as a
normal so called CAMG chunk, so PicBoot should handle bad values
properly (although I haven't tested this much.. :).

LIST
====

   Short form: L

   If this switch is specified, PicBoot will interpret the files in
the FILES argument as names of files containing a list of pictures (or
rather, argument lines). PicBoot will then randomly select one of the
lines in the selected file, and process it almost like a normal argument
line. The only difference is that you can't use the DETACH, DELAY or
PATCH arguments. These arguments may not be specified in a listfile (no
point in doing it anyway).

   The listfile is an ASCII (text) file with a simple layout. On the
first line you specify the number of argument lines in the file. This is
usually <number of lines in file>-2 (one line is occupied by the count,
and the other is the last linefeed). If this value is zero, then
PicBoot will exit silently. The rest of the file is simply the
argument lines to choose from. An example:

     4
     Work:Pics/Comics/Calvin02.Pic MODEID 137220
     Work:Pics/Comics/Calvin03.Gif
     Work:Text/MoreCalvins.txt LIST CENTER ON
     Work:Pics/Misc/#?.Gif

   Note that any arguments specified from the CLI, or in any previous
listfile, will be taken as the new default value. In the listfile you
may alter this default. This does not include the LIST argument
(ofcourse). It is always turned off before parsing a line.

       Warning: Since you may enter a new listfile within a listfile,
you can be caught in an endless loop, constantly changing (maybe to the
same) listfile. No checking for this is done. Also, since there is no
CLI-window around, you have no chance to send PicBoot any CTRL-C, if
PicBoot should happen to listen to this. You have been warned! :)

       Note: A line in a listfile may not be more than 512 chars, or
it will be truncated when read. This shouldn't cause any problems I
think..

CENTER
======

   Short form: C

   Possible arguments: YES, ON, NO, OFF. Default is NO.

   If this switch is on (argument is YES or ON), PicBoot will center
the picture. This centering should work fine for most screen modes, but
one can never now.. :) If a screen promotor is active, then
PicBoot can get it wrong (when the screen is opened in another mode
than PicBoot had asked for).

DEFAULT
=======

   Short form: DEF

   Possible arguments: YES, ON, NO, OFF. Default is NO.

   If this switch is on (argument is YES or ON), PicBoot will force
the picture to use the default.monitor, regardless of what was actually
stored in the picture (in the CAMG chunk). This is needed since very
early in the startup, default.monitor is the only monitor available
(e.g.  multiscan.monitor is normally not available). In the future, I
might add more types of "forcing" (e.g. force a picture to PAL, NTSC or
whatever that might be useful).

   This switch also acts on the MODEID parameter, if specified.

AUTOSCROLL
==========

   Short form: AS

   Possible arguments: YES, ON, NO, OFF. Default is NO.

   If this switch is on (argument is YES or ON), the OS 2.0+
autoscrolling of screens will be enabled.

       Note: During boot, this switch may make the actual display a
bit smaller than normally possible. There is nothing I can do about
that... :) You can, however, by ensuring that ENV: is properly set up
before PicBoot is started. Or you could try the VIDEOOVERSCAN switch.

VIDEOOVERSCAN
=============

   Short form: VO

   Possible arguments: YES, ON, NO, OFF. Default is NO.

   If this switch is on (argument is YES or ON), the visible size of the
opened screen will be as large as the system can handle (assuming the
picture is large enough). Forces AUTOSCROLL to YES.

DELAY
=====

   Short form: DL

   A "problem" with PicBoot is that the Workbench screen first
opens, and then processes the Sys:WBStartup drawer, which takes a
little time. This means that the picture PicBoot shows disappear
before the boot is complete. To avoid this problem, the DELAY switch
can be use to specify the number of ticks (there are 50 ticks each
second) PicBoot will wait after the Workbench screen have opened.

   However, this isn't perfect. When the Workbench screen opens, the
PicBoot screen must be brought back to the front again. This causes a
little "flicker". To avoid this, use the PATCH parameter as well (this
feature requires OS 3.0+ to work).

   There is a special delay value, 0, which causes PicBoot to wait
until you either press any mouse button, or another program sends
PicBoot a break signal (CTRL-C). The program StopPicBoot was written
to do this.

PATCH
=====

   Short form: P

   If this switch is specified, PicBoot will install a patch in
Intuition, so that the Workbench screen (or rather, any screen
opened, that explicitly doesn't say that the screen shouldn't open
behind the others) doesn't open in front of the PicBoot screen. This
removes the "flicker" that normally occurs when using the DELAY option.
For this option to be useful, the DELAY parameter must be used as well.

       Note: This option only works on OS 3.0 or higher. This is due
to the OS (as far as I know), and there is nothing I can do about it
(tech note: Workbench in OS 2.0x doesn't seem to call the open screen
function via the external library vector).

       Note: This kind of patching is not a recommended thing to do.
Programs should not do temporary patches like this. However, to avoid
the flickering, there is no alternative.. :)

       Note: In case some other program patches the same function
after PicBoot have installed its patch - and you don't have a program
like e.g. SetMan installed - then PicBoot will leave a small memory
allocation behind (6 bytes), to avoid any problems.

DETACH
======

   Short form: D

   If this switch is specified, PicBoot will detach from its calling
CLI when the picture is fully loaded and displayed. If you specify this
option, you shouldn't "Run" PicBoot. This option will reduce memory
fragmentation, and will ensure that the picture gets loaded quickly. I
don't think this feature will cause any problems, but I added the
switch just in case.

Known problems
**************

   I do not know of any real bugs in PicBoot. However, certain parts
of the program may still contain bugs. E.g.,  pictures that have a mask
bitplane (mskHasMask) are supported, but since I only have one
(compressed) picture that have a mask, there might be a bug in that
code (can't test it properly).  Please report any problems!

   Currently there is no support for SHAM, PCHG and similar "special"
pictures. I'm not sure if this could be implemented in a "clean" way
(that would work on future systems etc). These pictures aren't that
common, and I have an Amiga with AA-graphics, so... :) Color cycling is
currently ignored (I have no need for it).

   Interlaced GIF pictures aren't supported, since I don't have any such
picture (well, actually I have ONE :). Besides, the decompression of
such pictures would be slower anyway.

       PicBoot doesn't remap GIF files in any way. Even if you have
ECS, GIF files can still be useful. This is because a GIF file can have
from 2 to 256 colors (inclusive). Thus, if you have a program that can
save a 16-color picture as a 16-color GIF file, there will be no
problem to view it with PicBoot.

       PicBoot doesn't make use of any chunky to planar hardware, if
it should happen to be installed (e.g. Aikiko). Anyone who have it, so
I can test it if I should decide implement it? :) It would be fairly
simple to do, since my own chunky to planar routines have very similar
restrictions..  :)

   The "best mode" routine used in the GIF reader isn't good at all
(this includes the ROM function in OS 3.0+! :). I suggest you use the
MODEID parameter instead (Correction: The ROM function isn't good when
there are several different monitors to choose from. If only one or two
(similar) monitors are available, then the result is usually rather
good).

   Pictures with more than 8 bitplanes are currently not supported by
PicBoot.

   The centering for (some?) Super72 screens doesn't work. I suspect
this is an OS-bug (I know that PicBoot calculates a reasonable
offset, which Intuition seems to ignore).

StopPicBoot
***********

       StopPicBoot is a small program that simply tells PicBoot to
quit, if it should happen to be in memory. This is useful in
combination with the DELAY option. If this is set to 0, PicBoot
expects someone to tell it when it is time to exit, and this is what
StopPicBoot does.

   By having StopPicBoot in Sys:WBStartup, then PicBoot will
close its screen when the boot process almost complete (the tooltype
STARTPRI should be very low (-120 or so), so that StopPicBoot is
started as the last program)

GetModeID
*********

       GetModeID is a simle program that shows a Asl or
ReqTools screenmode requester, whichever is available. The program
will then print out the decimal identifier for the selected screenmode,
suitable for use together with the MODEID parameter. This program can
only be used from a Shell. Example usage:

       PicBoot Island.Gif MODEID `GetModeID`

   This will first show a screenmode requester (if you have one, that
is), and then show the GIF-picture in the selected screenmode.

UnpackILBM
**********

       UnpackILBM is another simple program (at least in theory...
:). It will take any IFF ILBM picture and unpack the so called BODY
chunk in it (this is the actual image data). This means that e.g.
PicBoot will be able to display that image a little faster, at least
if loading it from some fast media. Or, if you use
PPShow/ShowIFF, you could repack the picture with
PowerPacker/Xpk, to maximize the compression (as the compression
used in IFF ILBM isn't a very efficient one. But on the other hand, it
is rather fast and simple). But then PicBoot won't be able to load
them.. :) Example usage:

       UnpackILBM Island.Pic Island.Pic.NoComp
       UnpackILBM Island.Pic

   The first example till unpack the picture to a new one, while the
other will - via a temprary file - overwrite the original picture with
the uncompressed version.

       Note: I haven't tested this program that much. I've converted
a few pictures, so it seems to work fine (at least when there aren't any
errors), but one can never now.. Please report any problems!

       Note: This program doesn't strip any information. All chunks
will remain. The picture data is only decompressed.

Author contact
**************

       PicBoot was written by Magnus Holmgren. If you have any
comments etc, feel free to send me a note. You can reach me via
internet on this address:

     [e-mail]

   Fido-net messages should go to "Magnus Holmgren",
2:204/[e-mail].  Snail mail should reach me if you write the
following address on the envelope:

     Magnus Holmgren
     Kvarnbergsvägen 4
     S-444 47  Stenungsund
     SWEDEN

Version history
***************

Version 1.00
============

   Release date: 08 Feb 93

   *  Initial release.

Version 1.01
============

   Release date: 14 Feb 93

   *  PicBoot would sometimes read past the end of the picture-list
     file, although the file was correct. Also, the last picture would
     never be showed.  Fixed (thanks to Daniel Joseph Oak for
     reporting).

   *  Did some tweeking, to make the program smaller. The total gain
     was eaten up by improved error messages though. PicBoot will now
     more accurately report why the display didn't open.

   *  Added support for masked ILBMs, since I discovered that I had
     such a picture anyway. :) Since I only have one picture, its hard
     to tell if it really works, but it seems to be ok at least.

   *  The autoscrolling of the screen didn't work. Fixed (so now you
     can view pictures larger than the screen, by moving the invisible
     mouse-pointer).

   *  Added the CENTER switch.

Version 1.02
============

   Release date: 21 Feb 93

   *  Added the DEFAULT switch. As Bradley Yen pointed out for me,
     there is (normally) only one monitor available early in the
     startup, and that is default.monitor (and what default.monitor is
     can vary. It can e.g. be PAL or NTSC). This switch will make the
     picture use the default.monitor, regardless what it was saved in.

   *  Autoscrolling of screen disabled again, since this would make some
     overscanned pictures clipped, even if this wasn't needed.

   *  A bug in the init code fixed.

Version 1.03
============

     Release date: 15 Oct 93

   *  If an error occured, any black "cover screen" (BLACK option)
     wasn't closed.  Fixed.

   *  "Ported" to Macro68. At the same time, the code was cleaned up a
     little. All this saved more than 100 bytes from the program. Most
     of it eaten up by the improvements though.. :)

   *  Added the MODEID parameter. rtGetModeID is included to make the
     use of this parameter easier.

   *  Docs rewritten using Texinfo.

   *  Pictures with mskHasMask were reported to have an "error in
     compressed BODY chunk", due to a bug. Sorry, but I don't have many
     pictures to test this code with.. :)

   *  AUTOSCROLL switch added, so that you can scroll around in large
     pictures. Mostly useful when PicBoot is used from the Shell.
     During boot, this can cause the picture to be clipped when it
     isn't necessary.

   *  PicBoot will now move the screen to the back before closing it
     (this makes the closing faster). Not needed during boot, but... :)

   *  List files much improved! Each line will be parsed almost like
     the normal arguments. Old files should work fine, as long as no
     filename contains spaces, in which case those lines need to be
     quoted.

   *  Altered command line syntax slightly. Needed because of the new
     listfile format. Technical note: I'm using a poorly documented
     feature of AmigaDOS: The /T specifier. If the argument following
     the keyword is YES or ON, the switch is turned on, if it is OFF or
     NO, the switch is off.  Any other arguments causes an error.
     Testing revealed the true nature of this specifier... :)

   *  Removed the "You need OS 2.04+" error message. An (Exec) Alert
     will be shown instead.

   *  PicBoot will now random-select among the FILES arguments, even
     if the LIST argument have been used (previously, only the first
     file was used).

   *  VIDEOOVERSCAN switch added. Makes the visible area as large as the
     system can handle. Requested by Stefan Boberg.

   *  Screen centering improved. Should work fine with any screen mode
     now (but if you promote the screen, PicBoot will probably get it
     wrong. Unless the promotor also "promotes" QueryOverscan() :).

Version 2.0
===========

   Release date: 29 Mar 94

   *  BLACK argument removed. Not needed any more, since PicBoot now
     will first allocate the needed memory, decode the picture into
     this memory, and then open the screen. This makes the screen
     opening/closing a little faster too (practically instaneous on my
     A4000/040).

   *  Pictures (or rather, brushes) that were less than 16 pixels wide
     wouldn't decompress properly... :)

   *  Added support for the CMAPOK flag in the BitMapHeader.bmh_Flags
     (previously called bmh_Pad) field (if this flag is set it
     indicates that the color map contains 8 bits/color rather than 4
     bits/color).

   *  Major code cleanup. Made the program somewhat larger, but... :)

   *  GIF support added. Should be a little faster than PPShow.. :)

   *  The MODEID argument wasn't properly "passed on" to any following
     listfile(s).

   *  Rewrote rtGetModeID into GetModeID, that first checks for
     Asl, and then tries with ReqTools before giving up. This new
     version is in C, compiled with DICE, without any startup code, and
     is fully residentable. :) See GetModeID.

   *  Included UnpackILBM, that takes any IFF ILBM file (with a BODY
     chunk, i.e. a normal picture) and writes it with an uncompressed
     BODY instead. Written upon user request. See UnpackILBM.

Version 2.1
===========

   Release date: 14 May 94

   *  The DEFAULT parameter didn't do anything. Fixed

   *  UpackILBM and GetModeID updated a little. Version string
     added, recompiled with DICE 3.0 and some other minor changes.

Version 2.2
===========

   Release date: 12 Jul 94

   *  If the listfile was too short (i.e. not enough number of lines in
     it), PicBoot would crash.

   *  Made the detaching code more system friendly. I hope this will
     fix the problems a few users have had.

   *  A few minor bugs fixed + some minor optimizations...

   *  If the number on the first line in the listfile is 0, then
     PicBoot will exit silently. Now why did I add this... >;)

   *  Improved the random number algorithm.

   *  Added the DELAY parameter.

   *  Added the PATCH parameter.

   *  Tweeked the GIF-unpacker a little. Found yet another Macro68
     (V3.170) bug while doing that.. :/ (Watch out for bra.l to other
     sections/modules when generating code for the 68020+. The branch
     target is not correct. :)

Version 2.3
===========

   Release date: 30 Aug 94

   *  Rewrote startup code and argument parser in C, for easier
     maintainance (and to simplify the implementation of some of the
     features below).

   *  You can now also specify a directory (with optional pattern
     matching), and PicBoot will randomly select among the files
     found. As usual, you can use this feature whereever PicBoot used
     to expect a file name.

   *  If the comment field of a file that PicBoot will read (i.e. a
     list file or a picture) starts with the string "*PicBoot*: " (case
     sensitive), then the rest of the comment is assumed to be
     arguments, to be parsed like they had been found in a list file.

   *  UnpackILBM will not delete the temp file if it couldn't be
     renamed to the original.

   *  Removed a piece of debug code in the OpenScreen() patch (it
     flashed the screen). Harmless, but annoying.. :)